home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / ODFDev / ODF / Found / FWString / SLStrRep.h < prev    next >
Encoding:
Text File  |  1996-09-17  |  14.2 KB  |  354 lines  |  [TEXT/MPS ]
  1. //========================================================================================
  2. //
  3. //    File:                SLStrRep.h
  4. //    Release Version:    $ ODF 2 $
  5. //
  6. //    Copyright:    (c) 1993 - 1996 by Apple Computer, Inc., all rights reserved.
  7. //
  8. //========================================================================================
  9.  
  10. #ifndef SLSTRREP_H
  11. #define SLSTRREP_H
  12.  
  13. #ifndef SLLOCALE_H
  14. #include "SLLocale.h"
  15. #endif
  16.  
  17. // Export or Import functions for CFM-68K [sfu]
  18.  
  19. #if defined(FW_ODFLIB_IMPORT)
  20. #pragma import on
  21. #elif defined(FW_ODFLIB)
  22. #pragma export on
  23. #endif
  24.  
  25. FW_EXTERN_C_BEGIN
  26.  
  27. // NOTES
  28. //
  29. //    StringReps are reference counted, so they are always heap allocated.
  30. //    This allows us to make them be an opaque data structure.
  31. //    Since they are opaque, ALL access is through accessor functions.
  32. //    This means that storage allocation is under complete control
  33. //    of the SLStrRep subsystem.
  34.  
  35. //========================================================================================
  36. //    Forward Declarations
  37. //========================================================================================
  38.  
  39. struct ODIText;
  40.  
  41. void FW_PrivInitStringData();
  42. FW_Locale FW_PrivGetDefaultLocale();
  43.  
  44. //========================================================================================
  45. //    STRUCT FW_SPrivStringRep
  46. //========================================================================================
  47.  
  48. struct FW_SPrivStringRep;
  49.     // An opaque data structure!
  50.     
  51. typedef FW_SPrivStringRep* FW_HString;
  52.     // A handle to a string. The preferred way to reference a PrivStringRep
  53.  
  54. //========================================================================================
  55. //    FW_SPrivStringRep Member Functions
  56. //========================================================================================
  57.  
  58. FW_HString FW_PrivString_AcquireEmptyString();
  59.     // Returns a rep for an empty (roman, english) string.
  60.     // The rep is shared by all empty strings.
  61.  
  62. FW_HString FW_PrivString_AcquireEmptyStringWithLocale(FW_Locale locale, FW_PlatformError* error);
  63.     // Returns a rep for an empty string from specified locale.
  64.     // This always creates a new rep.
  65.  
  66. void    FW_PrivString_Acquire(FW_HString self);
  67.     // Increments the reference count
  68.  
  69. void    FW_PrivString_Release(FW_HString self);
  70.     // Decrements the reference count.
  71.     // If the reference count is zero, the client will probably want
  72.     // to immediately call FW_PrivString_Delete, though the call
  73.     // may be deferred if the client wants to reuse the structure.
  74.     
  75. FW_HString FW_PrivString_LockString(FW_HString self, FW_PlatformError* error);
  76.     // Locks the string (if not already locked) and returns the locked rep.
  77.  
  78. FW_HString FW_PrivString_NewRepWithStaticBuffer(unsigned char* buffer,
  79.                                     FW_ByteCount bufferLen);
  80.     // Allocate a new rep that uses the given static buffer
  81.     // This function may fail due to insufficient memory, if so NULL is returned.
  82.     // No error code is returned because the intention is that this function
  83.     // is to only be called from a constructor's initializer list
  84.  
  85. void FW_PrivString_ReleaseStaticBuffer(FW_HString self, FW_PlatformError* error);
  86.     // Release use of a static buffer.
  87.  
  88. void FW_PrivString_Retrieve(FW_HString self, 
  89.             char* destination, 
  90.             FW_ByteCount numberChars, 
  91.             FW_BytePosition position);
  92.     // Retrieve a range of bytes from the string, placing them in destination.
  93.  
  94. FW_HString FW_PrivString_Delete(FW_HString self, 
  95.             FW_ByteCount numberBytes, 
  96.             FW_BytePosition position, 
  97.             FW_PlatformError* error);
  98.     // Delete a range of bytes from the string.
  99.  
  100. FW_ByteCount    FW_PrivString_GetByteLength(FW_HString self);
  101.     // Returns the number of bytes holding character codes (not the number of characters!)
  102.  
  103. FW_ByteCount    FW_PrivString_GetCapacity(FW_HString self);
  104.     // Returns the current capacity for bytes, which may be expanded using SetCapacity
  105.  
  106. FW_CharacterCount    FW_PrivString_GetCharacterLength(FW_HString self, FW_PlatformError* error);
  107.     // Returns the number of characters in the string.
  108.     // For some character sets this may be relatively expensive!
  109.     // For efficiency, if GetByteLength will suffice, use it.
  110.  
  111. FW_HString    FW_PrivString_SetCapacity(FW_HString self, 
  112.                                       FW_ByteCount newCapacity, 
  113.                                       FW_PlatformError* error);
  114.     // Sets the new capacity, which is the largest number of bytes
  115.     // that may be used for holding character codes.
  116.     
  117. ODIText*    FW_PrivString_RevealODIText(FW_HString self);
  118.     // Reveals the ODIText data structure.
  119.     // This function is provided to make it efficient to pass
  120.     // strings to OpenDoc APIs that are defined with "in ODIText"
  121.     // parameters.  Clients must not modify the revealed ODIText
  122.     // data structure, or all hell may break loose. ;>
  123.     
  124. const char*    FW_PrivString_RevealBuffer(FW_HString self);
  125.     // Reveals the character buffer.
  126.     // This function is provided to make it efficient to directly
  127.     // process the bytes of storage.  Clients must not modify the revealed buffer,
  128.     // or all hell may break loose. ;>
  129.     // NOTE: the buffer is probably NOT nul-terminated!!
  130.  
  131. FW_Locale* FW_PrivString_RevealLocale(FW_HString self);
  132.     // Reveals the locale.
  133.     // Used when creating a TextReader.
  134.  
  135. void FW_PrivString_GetLocale(FW_HString self, FW_Locale* locale);
  136.     // Return this string's locale.
  137.     
  138. FW_HString FW_PrivString_Truncate(FW_HString self, 
  139.                                 FW_BytePosition bytePosition, 
  140.                                 FW_PlatformError* error);
  141.     // Removes the given run of bytes from the current contents.
  142.     // It is the client's responsiblity to insure that no double byte characters
  143.     // are broken!
  144.     
  145. //----------------------------------------------------------------------------------------
  146. //    Insert Functions
  147. //----------------------------------------------------------------------------------------
  148.  
  149. FW_HString FW_PrivString_InsertBytes(FW_HString self, 
  150.                                 const char* bytes, 
  151.                                 FW_ByteCount numberBytes,  
  152.                                 FW_BytePosition position, 
  153.                                 FW_PlatformError* error);
  154.     // Inserts the given bytes at the given byte position.
  155.     // It is the client's responsiblity to insure that bytePosition does not
  156.     // split a double byte character! Hint: bytePosition should have been determined
  157.     // using a function known to return valid character offsets.
  158.  
  159. FW_HString FW_PrivString_InsertODIText(FW_HString self, 
  160.                                 ODIText* text,
  161.                                 FW_BytePosition position, 
  162.                                 FW_PlatformError* error);
  163.     // Inserts the given text at the given byte position.
  164.     // It is the client's responsiblity to insure that bytePosition does not
  165.     // split a double byte character!
  166.  
  167. FW_HString FW_PrivString_InsertStringRep(FW_HString self, 
  168.                                 FW_HString other, 
  169.                                 FW_BytePosition position, 
  170.                                 FW_PlatformError* error);
  171.     // Inserts the given text at the given byte position.
  172.     // It is the client's responsiblity to insure that bytePosition does not
  173.     // split a double byte character!
  174.  
  175. //----------------------------------------------------------------------------------------
  176. //    Replace Functions
  177. //----------------------------------------------------------------------------------------
  178.  
  179. FW_HString FW_PrivString_ReplaceAllStringRep(FW_HString self, 
  180.                                         FW_HString text, 
  181.                                         FW_PlatformError* error);
  182.     // Replaces the current contents with the given text.
  183.  
  184. FW_HString FW_PrivString_ReplaceAllODIText(FW_HString self, 
  185.                                         ODIText* text, 
  186.                                         FW_PlatformError* error);
  187.     // Replaces the current contents with the given text.
  188.  
  189. FW_HString FW_PrivString_ReplaceAllBytes(FW_HString self, 
  190.                                         const char* bytes, 
  191.                                         FW_ByteCount numberBytes, 
  192.                                         FW_PlatformError* error);
  193.     // Replaces the current contents with the given text.
  194.  
  195. //----------------------------------------------------------------------------------------
  196. //    Append Functions
  197. //----------------------------------------------------------------------------------------
  198.  
  199. FW_HString FW_PrivString_AppendODIText(FW_HString self, 
  200.                                         ODIText* text, 
  201.                                         FW_PlatformError* error);
  202.     // Appends the given text onto the end of the current contents.
  203.  
  204. FW_HString FW_PrivString_AppendStringRep(FW_HString self, 
  205.                                         FW_HString text, 
  206.                                         FW_PlatformError* error);
  207.     // Appends the given text onto the end of the current contents.
  208.  
  209. FW_HString FW_PrivString_AppendBytes(FW_HString self, 
  210.                                     const char* bytes, 
  211.                                     FW_ByteCount numberBytes, 
  212.                                     FW_PlatformError* error);
  213.     // Appends the given bytes onto the end of the current contents.
  214.  
  215. //----------------------------------------------------------------------------------------
  216. //    Prepend Functions
  217. //----------------------------------------------------------------------------------------
  218.  
  219. FW_HString FW_PrivString_PrependODIText(FW_HString self, 
  220.                                         ODIText* text, 
  221.                                         FW_PlatformError* error);
  222.     // Prepends the given text onto the beginning of the current contents.
  223.  
  224. FW_HString FW_PrivString_PrependStringRep(FW_HString self, 
  225.                                         FW_HString text, 
  226.                                         FW_PlatformError* error);
  227.     // Prepends the given text onto the beginning of the current contents.
  228.  
  229. FW_HString FW_PrivString_PrependBytes(FW_HString self, 
  230.                                     const char* bytes, 
  231.                                     FW_ByteCount numberBytes, 
  232.                                     FW_PlatformError* error);
  233.     // Prepends the given bytes onto the beginning of the current contents.
  234.  
  235. //----------------------------------------------------------------------------------------
  236. //    Export Functions
  237. //----------------------------------------------------------------------------------------
  238.  
  239. void FW_PrivString_ExportCString(FW_HString self, char* buffer);
  240.     // Copy contents of this string to external buffer as a NUL-terminated C string.
  241.  
  242. void FW_PrivString_ExportPascalString(FW_HString self, FW_PascalChar* buffer);
  243.     // Copy contents of this string to external 'Pascal' buffer.
  244.  
  245. //----------------------------------------------------------------------------------------
  246. //    Monocasing Functions
  247. //----------------------------------------------------------------------------------------
  248.  
  249. FW_HString FW_PrivString_ToUpper(FW_HString self, FW_PlatformError* error);
  250.     // Convert all lowercase characters to uppercase.
  251.  
  252. FW_HString FW_PrivString_ToLower(FW_HString self, FW_PlatformError* error);
  253.     // Convert all uppercase characters to lowercase.
  254.  
  255. //----------------------------------------------------------------------------------------
  256. //    Searching and Substitution Functions
  257. //----------------------------------------------------------------------------------------
  258.  
  259. FW_Boolean FW_PrivString_FindCharacter(FW_HString self, 
  260.                         FW_LChar character, 
  261.                         FW_ByteCount *foundPosition, 
  262.                         FW_ByteCount startPosition,
  263.                         FW_FindDirection direction);
  264.     // Find the first occurence of character, starting the search at startPosition.
  265.     // Return false if the character is not found.
  266.  
  267. FW_Boolean FW_PrivString_FindSubString(FW_HString self, 
  268.                         FW_HString subString, 
  269.                         FW_ByteCount *foundPosition, 
  270.                         FW_ByteCount startPosition);
  271.     // Find the first occurence of substring, starting the search at startPosition.
  272.     // Return false if the substring is not found.
  273.  
  274. FW_HString FW_PrivString_Substitute(FW_HString self, 
  275.                         FW_HString searchString, 
  276.                         FW_HString substitutionString, 
  277.                         FW_Boolean* wasReplaced, 
  278.                         FW_PlatformError* error);
  279.     // Find the first occurence of substring, starting the search at startPosition.
  280.     // If the substring is found, replace it with the substitution string.
  281.     // Set wasReplace to false if the substring was not found.
  282.  
  283. FW_StringCompareResult FW_PrivString_Compare(FW_HString string1, FW_HString string2);
  284.     // Compare the two strings (taking into account locality of the strings).
  285.  
  286. //----------------------------------------------------------------------------------------
  287. //    Number Conversion Functions
  288. //----------------------------------------------------------------------------------------
  289.  
  290. FW_HString FW_PrivString_SignedIntegerToDecimalString(FW_HString self, 
  291.                                                     long integer, 
  292.                                                     FW_PlatformError* error);
  293.     // Given a signed long integer, create a string with it's decimal representation
  294.  
  295. FW_HString FW_PrivString_UnsignedIntegerToDecimalString(FW_HString self, 
  296.                                                     unsigned long integer, 
  297.                                                     FW_PlatformError* error);
  298.     // Given a unsigned long integer, create a string with it's decimal representation
  299.  
  300. FW_HString FW_PrivString_UnsignedIntegerToHexadecimalString(FW_HString self, 
  301.                                                     unsigned long integer, 
  302.                                                     FW_PlatformError* error);
  303.     // Given a unsigned long integer, create a string with it's hexadecimal representation.
  304.     // The uppercase letters A-F are used.
  305.  
  306. long FW_PrivString_DecimalStringToSignedInteger(FW_HString self);
  307.     // Given a string, return the integer.
  308.     // Assumes the string contains a valid decimal representation.
  309.     // The string is parsed to the first non-decimal character (including '-').
  310.     // Zero is returned if the first character is not a decimal character.
  311.     // No error is returned under any condition. 
  312.  
  313. unsigned long FW_PrivString_DecimalStringToUnsignedInteger(FW_HString self);
  314.     // Given a string, return the unsigned integer.
  315.     // Assumes the string contains a valid decimal representation.
  316.     // The string is parsed to the first non-decimal character (not including '-').
  317.     // Zero is returned if the first character is not a decimal character.
  318.     // No error is returned under any condition.
  319.  
  320. unsigned long FW_PrivString_HexadecimalStringToUnsignedInteger(FW_HString self);
  321.     // Given a string, return the unsigned integer.
  322.     // Assumes the string contains a valid hexadecimal representation.
  323.     // The string is parsed to the first non-hexadecimal character
  324.     // (including a-f, A-F, not including '-').
  325.     // Zero is returned if the first character is not a decimal character.
  326.     // No error is returned under any condition.
  327.  
  328. FW_HString FW_PrivString_DoubleToString(FW_HString self, 
  329.                                         double value, 
  330.                                         short fractionalDigits,
  331.                                         FW_PlatformError* error);
  332.     // Given a floating point value, create a string with it's decimal representation
  333.     // fractionalDigits is the number of digits to be shown after the decimal point.
  334.     // All digits to the left of the decimal point are shown (sci notation is never used).  
  335.  
  336. double FW_PrivString_StringToDouble(FW_HString self);
  337.     // Given a string, return the double.
  338.     // Assumes the string contains a valid floating point representation.
  339.     // Zero is returned if the first character is not a decimal character (include '-').
  340.     // No error is returned under any condition.
  341.  
  342. FW_EXTERN_C_END
  343.  
  344. // For CFM-68K [sfu]
  345.  
  346. #if defined(FW_ODFLIB_IMPORT)
  347. #pragma import off
  348. #elif defined(FW_ODFLIB)
  349. #pragma export off
  350. #endif
  351.  
  352. #endif
  353.  
  354.